widget: Clarify docs on gtk_widget_set_double_buffered()

Also make them more scary so people really really don't use it as a
random knob when trying to make things go fast.

//bugzilla.gnome.org/show_bug.cgi?id=750505

diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 5da33ec78a3690606196190b8013b90d4c01c268..4c03956e5472c03f4fb07b735a942ccd8d0ad8e0 100644 (file)
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -9336,11 +9336,16 @@ gtk_widget_get_app_paintable (GtkWidget *widget)
  * pixmap will not happen automatically (as it is done in
  * gdk_window_begin_paint_region()).
  *
- * Since 3.10 this function only works for widgets with native
- * windows.
- *
- * Deprecated: 3.14: This does not work under non-X11 backends,
- * and it should not be used in newly written code.
+ * In 3.10 GTK and GDK have been restructured for translucent drawing. Since
+ * then expose events for double-buffered widgets are culled into a single
+ * event to the toplevel GDK window. If you now unset double buffering, you
+ * will cause a separate rendering pass for every widget. This will likely
+ * cause rendering problems - in particular related to stacking - and usually
+ * increases rrendering times significantly.
+ *
+ * Deprecated: 3.14: This function does not work under non-X11 backends or with
+ * non-native windows.
+ * It should not be used in newly written code.
  **/
 void
 gtk_widget_set_double_buffered (GtkWidget *widget,